Chapter 4: continued

DocServer Documentation

DocServer is a tightly-integrated, scriptable application that gives you fast and easy access to every UserTalk verb, operator and structure keyword (e.g. "if", "try"). Some companies have also created DocServer pages for their application verbs. There are many ways to access DocServer.

Let's lookup the "dialog.ask" verb that was used in the previous section. From the "On-Line Docs" submenu of the "UserLand" menu, choose "Open DocServer" (or use the Cmd-= keyboard equivalent). Type "dialog.ask" (no quotes) and click OK. Frontier will launch DocServer, bring it to the front, and display the page for this verb. (If you have trouble, verify that DocServer is in the UserLand Utilties Folder.) DocServer includes the verb Syntax, Parameters, a description of the Action, what the verb Returns, Errors if any, one or more Examples, plus Notes and See Also. The See Also items are in a menu, so you can easily navigate to related verbs.

From within DocServer, you can jump directly to a verb. We learned about "try" earlier in the chapter. Perhaps you remember that there's a way to get the error message, but don't remember the details? Let's check DocServer. Select "Jump to Verb" from the "File" menu, or use the Cmd-J keyboard equivalent. Type "try" and click OK. Scroll down to the notes section; there it is: "tryError".

DocServer makes it easy to navigate to related verbs. Notice that the See Also items are in a menu. In this case there is only one item, "scriptError". Select it. Voila! DocServer also keeps track of recent items you have viewed; see the "History" menu.

To save yourself some typing, you may want to bring this information back to Frontier. From the "Copy" menu, select "Syntax". You can bring Frontier to the front in all the usual Macintosh ways, or select "Switch to Frontier" from the "Frontier" menu. Now, you can paste the information into a Frontier script. (Feel free to try it, though be careful which window is frontmost.)

Frontier has a shortcut for quickly locating an item in DocServer: hold down the Control key (careful, Control not Command) and double-click on the name of any verb in any Frontier window. (Note that this shortcut is often abbreviated as "control2click.") Frontier will bring DocServer to the front and display that verb's page. This technique is most useful when you are reviewing a script written by someone else, or have already typed the command into your script but need to check some details. Let's try it. Type Cmd-J (within Frontier) and then "examples.counter" (no quotes). This simple example script just counts to 10, displaying the number with "window.msg". Wait, how is that different than the normal "msg" verb? Hold Control and double-click on "window.msg" in the script. The DocServer page appears!

DocServer has many useful menu items not covered here; explore them to see which ones fit your style of work. One tip: "Find" looks in the text, so it is much slower than "Jump." As you probably noticed, there are buttons in the DocServer window to go to the previous and next entry (alphabetically).

The "File", "SeeAlso" and "History" menus are built-into DocServer, the other menus are implemented using Frontier's Menu-Sharing protocol. You can edit these menus and customize DocServer! In fact, some of the existing features that were not in the 1.0 release were created by members of the scripting community and contributed to UserLand.

Documentation in Frontier

Frontier includes useful documentation right in the Object Database. One starting point is the "On-Line Docs" submenu in the "UserLand" menu:

Open DocServer...
-
Browse On-Line Index
Search On-Line Index
-
Object Database Map
Frontier Data Types
Frontier Verbs
Frontier Grammar

We've already looked at "Open DocServer", let's try the index. Select "Browse On-Line Index." The index resembles the index you might expect to find in a printed manual, with an added benefit: Command-double-click on the Object Database address to go to that location. Try this. From the "Outline" menu, select "Full Expand" so that you can see the entire index. Scroll until you see the following:

Backing up
   the importance of
      helptext.backingup
   Backup command in the UserLand menu
      helptext.userlandmenu
   making room for new backups
      samples.basicStuff.makeRoom

Hold the Command key and double-click on "helptext.backingup". Voila, the document appears in a Frontier window. The next item in the sub-menu prompts you for a search string, remembering your previous entry. Of course, when the Index window is frontmost, Frontier's normal search features also work.

The Object Database is a big place! See Chapter 6 for details. Especially when you are first learning Frontier, it's difficult to remember what things are where. How about a map? Select "Object Database Map". A window containing an outline of the database appears, and a new menu called "Map" is installed in the menubar.

Among other features, the menu has a special version of Cmd-J to Jump to any object listed on the map. Put the cursor on a line and select Cmd-J; Frontier will open the window for that object. (If another window is in front when you select Cmd-J, Frontier will switch to the Map outline.) If the outline is no longer in front, select Cmd-O to open it. (Frontier processes keyboard equivalents from right back to left, so the Map menu's shortcuts override these shortcuts in other menus.) One caution: the option to rebuild the map may take quite a bit of time.

When you are done with the map, select "Minimal Menus" from the "Suites" menu. This step will remove the "Map" menu and -- more importantly -- restore the standard behavior for Cmd-J and Cmd-O.

Next, choose "Frontier Data Types." Frontier will open the outline helptext.datatypes which lists all of the valid UserTalk datatypes. We will have more to say about datatypes later in this chapter.

Figure 7-1. Partial View of Frontier Datatypes Outline

As discussed earlier in the chapter, Frontier has hundreds of built-in verbs. How do you find what you need? Select "Frontier Verbs"; it opens the suites.doc.verblist outline. Scroll through to see the categories. Pick one that looks interesting and expand to see the verbs, complete with parameters. (Double-click on any item marker to expand or contract.) In the DocServer section, we learned about Control-double-click, try it here!

We suggest making this outline part of your daily routine. When you know the verb but don't remember the parameters, look them up here or in DocServer. When you want to know if Frontier has a verb for a certain task you would like to accomplish, look at the verbs listed in the appropriate category. If you don't see what you need, use Frontier's Find and try various keywords or topics that might fit; the verb may be in a different category than you expect. For details on any verb, go from the outline to DocServer.

Figure 7-3. Part of the UserTalk Verb List

The last item in the "On-Line Docs" submenu takes you to an outline of UserTalk's formal grammar. It's likely to be completely uninteresting to the majority of script writers. Frontier appeals to novice and expert alike; the grammar is for those with a degree in Computer Science.